Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
The Problem & the Solution
When writing OpenDoc-based code, one often needs to create temporary objects that need to be freed, or acquire temporary references to objects that then need to be released. There are two pitfalls with this — the obvious one is that you have to remember to call 'delete' or 'Release' on every temporary object. The not so obvious one is that, if you are using the Except utility and an exception is thrown while a temporary is active, the rug will be pulled out from under you and you won't be able to issue the 'delete' or 'Release' call. This results in a memory or ref-count leak, unless you put in an exception handler whose job is to clean up these temporaries, which complicates your code and introduces even more room for subtle errors.
Here's an example of code that uses a temporary reference:
{
ODShape *s = frame->GetFrameShape(ev,kODNULL);
DoSomethingTo(s);
s->Release(ev);
}
We had to remember to call Release on s after we were through with it. And we still have the problem that, if DoSomething throws an exception, s will be left dangling. We could make the code exception-safe by rewriting it as:
{
ODShape *s = frame->GetFrameShape(ev,kODNULL);
TRY
DoSomethingTo(s);
CATCH_ALL
s->Release(ev);
RERAISE;
ENDTRY
s->Release(ev);
}
This makes the code more complicated (and larger), and you have to repeat the Release call twice. It's easy to get this wrong, resulting in code that works fine unless an exception is thrown, in which case it does the wrong thing. Since exceptions happen rarely in normal use, this results in spurious bugs. Ewww.
An elegant solution to the problem is to make use of stack-based C++ objects whose destructors will be called whenever they go out of scope, whether through exiting a block normally, or via an exception. Our exception library implements these, whether or not native C++ exceptions are supported, and calls them Destructos.
Using Destructos and some clever operator overloads, it's possible to make little objects that pretend to be pointers to other types of objects, and can be used just as though they were pointers. Unlike pointers, however, they clean themselves up automatically.
Using this facility, we can rewrite our routine as:
{
TempODShape s = frame->GetFrameShape(ev,kODNULL);
DoSomethingTo(s);
}
All we had to do was change “ODShape*” to “TempODShape”, and take out the Release call. The rest is the same. Although s is now an actual (stack-based) object, not a pointer, it can still be used as though it were an ODShape*. In particular, the following kinds of things are legal and do what you'd expect:
s->GetBoundingBox( ... )
xform->TransformShape(ev,s);
if( s != kODNULL ) ...
if( s ) ...
s = frame->GetUsedShape(ev,kODNULL); // Note that this does not release the shape s used to point to!
s = kODNULL;
The Release happens automatically when the block exits or if DoSomething throws an exception. Of course, if s holds a pointer to kODNULL, no Release operation will occur.
Using TempObjs and TempRefs
To use this facility, just #include <TempObj.h> in your source files. This gives you access to the following classes:
TempODFrame
TempODPart
TempODShape
TempODStorageUnit
TempODTransform
TempODWindow
TempODFocusSetIterator
TempODFrameFacetIterator
(Note that iterators are not ref-counted, so the Temp___Iterator classes delete the iterator object at the end instead of releasing it.)
If your compiler supports C++ templates (both CodeWarrior and Symantec C++ do) you can #define a symbol _USE_TEMPLATES_ before including TempObj.h. This will ensure that the header uses templates to implement these classes. This might make the implementation more efficient, and it also makes it much easier to extend the mechanism to new classes (see below.) If you can't or don't want to use templates, just don't define this symbol; the default is that the classes are implemented without using templates.
NOTE: There is a bug in the DR3 version of TempObj.h that will cause type-mismatch errors (probably at line 139) if you are using _USE_TEMPLATES_, unless you include <FrFaItr.xh> and <FacetItr.xh> before TempObj.h. In other words, include it as follows:
#include <FrFaItr.xh>
#include <FacetItr.xh>
#include <TempObj.h>
Pitfalls
The biggest mistake you can make in using this utility is forgetting that the object is always released. This can bite you if you need to use the object as the return value of a function:
ODShape *foo( ODFrame *frame ) {
TempODShape s = frame->GetFrameShape(ev,kODNULL);
DoSomething(s);
return s;
}
The ODShape is going to be released before it's returned, when the destructor of "s" is called. This is bad news, since the function will return either a pointer to a deleted object, or to an object whose ref-count is one too low. Either case is likely to cause a crash.
It's still nice to use a TempODShape in this function, for safety in case DoSomething throws an exception. We just want to tell "s" not to release itself when it's being returned. You can do this by setting the shape to kODNULL before returning it:
ODShape *foo( ODFrame *frame ) {
TempODShape s = frame->GetFrameShape(ev,kODNULL);
DoSomething(s);
ODShape *temp = s;
s = kODNULL; // s will not be released by the destructor now
return temp;
}
Of course, this is a kludge in that we have to store the value of s in a temporary to keep it from being lost. But there is a convenience method called DontRelease that will set the reference to NULL but return its previous value:
ODShape *foo( ODFrame *frame ) {
TempODShape s = frame->GetFrameShape(ev,kODNULL);
DoSomething(s);
return s.DontDelete(); // Note that we used ".", not "->"
}
Using Temp Iterators
The utility TempIter contains some extra classes that are TempObj's for OpenDoc iterator classes. In addition to managing the automatic deletion of the iterator itself, they also simplify the process of using the iterator (and shrink the resulting code.) For example:
since the iterator itself can be used as a synonym for its current object, and the "++" operator is the same as calling Next.
Adding New Classes
There are other classes you might want to have Temp____ objects available for.
If you're using templates (by defining _USE_TEMPLATES_ before including TempObj.h, as described above) this is very easy. You can declare a temporary reference to any type of ref-counted object by using the class TempRef<classname>. For instance:
TempRef<ODDraft> su = doc->AcquireDraft(ev);
You can also use temporary instances of non-ref-counted objects by using TempObj<class>:
TempObj<ODPeanutIterator> iter = peanut->GetIterator(ev);
If you're not using templates, you'll need to do some more work, adding several weird looking #defines and #includes. You can add these to the existing TempObj files, or in your own files. We'll describe the former case here.
Open TempObj.h. Scroll down to the comment that reads “Instantiations of TempObj and TempRef. Add your own if necessary.” Down past the “#else /* not _USE_TEMPLATES_*/” line, you'll see a series of groups of lines, each of which looks like:
#define _T_ ODFrame
#define _C_ TempODFrame
#include "TempRef.th"
Just add another one of these groups (it could be in TempObj.h, or you could put it into a separate header of your own) changing _T_ to the OpenDoc class and _C_ to the name of the temporary-reference class. If the OpenDoc class is not ref-counted, you'll need to #include "TempObj.th" instead.
Then open TempObj.cpp. Scroll down to the comment that reads “// Define the non-inline methods of the various template classes:”. Below that you'll see another list of #defines and #includes like the ones shown above. Again, add another one of these groups just like you did in TempObj.h.
You'll need to recompile TempObj.cpp. If this is in a separate utility library and not directly in your project, you'll need to build the library first (in CodeWarrior, open the library's project and choose the Make command.) If TempObj.h is precompiled, the very first thing you'll have to do is rebuild the precompiled header.
If, after adding a new class, you get a type-mismatch error in TempObj.h (probably at line 139) or in TempObj.th or TempRef.th, this indicates that you are trying to use TempObj with a class that is not a subclass of ODObject, or TempRef with a class that is not a subclass of ODRefCntObject. This can happen even if the class is correct, if the compiler hasn't seen the declaration of the class before the declaration of the temporary. In other words, the following is wrong:
class ODFoo;
TempRef<ODFoo> ref = ......;
#include "ODFoo.h"
At the time that the compiler instantiates the template for ODFoo, it does not know anything about the class, such as whether it is a subclass of ODRefCntObject, and will therefore give you type-check errors. You can avoid this by including the header for ODFoo before using the TempRef class.
